Improve research projects with Quarto

Case of study

MS Víctor Gauto

victor.gauto@ca.free.utn.edu.ar

GISTAQ (UTN-FRRe)

IIDTHH (UNNE, CONICET)

Instituto Gulich (UNC, CONAE)

Dr. Matías Bonansea

ICBIA (UNRC, CONICET)

Dr. Anabella Ferral

Instituto Gulich (UNC, CONAE)

Dr. Osvaldo Cardozo

IIDTHH (UNNE, CONICET)

Dr. Claudia Giardino

IREA (CNR)

2025-07-03

1 Outline

Introduction (\(\S\) 2)
Motivation (\(\S\) 3)
Tools (\(\S\) 4)
Conclusion (\(\S\) 5)
Future improvements (\(\S\) 6)
Resources (\(\S\) 7)

Slides available online

https://vhgauto.github.io/seminario2-gulich/

2 Introduction

Research project

To estimate water quality indicators in Paraná River middle basin for algorithm development using satellite remote sensing techniques

Collaborative website with automatic update, interactive and open source.

2.1 Front page

Authors
Affiliation
Other format (.pdf by typst)
Last modified date
Abstract
Keywords
More resources links

2.2 Table of content

Sections and subsections
Easy website navigation
Variable content according to the progress development

2.3 Notebooks

Source code description to promote reproducibility
Processing data methodology
External resources for further reading

2.4 References

Formatted references according to desired style (.csl)
Reference preview on main text

2.5 Maps, tables & interactive plots

Results visualization
Correlation between parameters exploration
Spectral properties description
Sample site location

Maps, tables and figures are updated automatically upon new measurements

2.6 Custom styling

Google Fonts

Lato |JetBrains Mono

Libre Bodoni |Bebas Neue

Accent colors

Web site

https://vhgauto.quarto.pub/gistaq-parana/

3 Motivation

Research Project progress.

%%{
  init: {
    'themeVariables': {
      'edgeLabelBackground': '#224289'
    }
  }
}%%

flowchart LR
    a1[Project<br>formulation] ==> a2[Start]
    a2 ====> |<span class="eos-icons--rotating-gear"></span>| a3[Main goal<br>is achieved]

    a3 ==> a4([Paper])
    a3 ==> a5([Conference])
    a3 ==> a6([Report])

classDef default stroke:#FFC0CB,color:#FFFFFF,fill:#224289;

Water sampling
Physicochemical analyses
Partial results assessment
Reference reading
Other tasks

While doing the Project, we lost vision on all the data collected and the knowledge acquired. Near the end we recognize this.

3.1 An alternative should be a…

Dynamic document to pour all the work, as is being made.
Flexible, so its adapts to the current project state.
Accesible, to check the latest results.
Easy to share with colleagues and third parties.
Unified reference search.
Automatically updated with new data, affecting plots, maps and tables.
Reproducible, with the entire script codes available.
All project members can work seamlessly without sync conflicts.
Consultation reference resource and to admire all the effort done so far.
Inspiration material for future papers and congress presentations.

4 Tools

R & Python: reading and data collection; processing and results storage; plots, tables and maps generation.
Git & GitHub: version control management and project members collaboration.
Quarto: to gather all the content in a website and to publish.
- Manuscript allows website creation with emphasis in reproducibility and targeted to scientific and academic documents.

4.1 R

targets allows automatic functions execution and dependencies management between them.

Check current workflow state and execute only outdated targets.

File monitoring and code re-execution upon change detection.

4.2 R

graph LR
  x2eb57580dd338e28(["excel"]) ==> x75ae8feee719d1e2(["datos_gis"])
  x27cf98eb0536b3cc(["fecha_actual"]) ==> x75ae8feee719d1e2(["datos_gis"])
  x0dc39fa9e42347ba>"reflectancia"] ==> x75ae8feee719d1e2(["datos_gis"])
  x2eb57580dd338e28(["excel"]) ==> x1a91c1978c7a143b(["datos_lab"])
  x38637a02f9b83fc8>"lab"] ==> x1a91c1978c7a143b(["datos_lab"])
  x29bd13377b9e6171>"archivo_excel"] ==> x2eb57580dd338e28(["excel"])
  x2eb57580dd338e28(["excel"]) ==> x27cf98eb0536b3cc(["fecha_actual"])
  xfabd587be49f2fed>"fecha"] ==> x27cf98eb0536b3cc(["fecha_actual"])
  xfabd587be49f2fed>"fecha"] ==> x38637a02f9b83fc8>"lab"]
  xc36834a08989fd92>"archivo_quarto"] ==> x0cceab94dc3cb992(["manuscrito"])
  xc856c5bfddbb40a5{{"bandas_s2"}} ==> xc5ec810879cc40ee>"recorte"]
  x9505d3eeeff3a790{{"puntos_muestreo"}} ==> xc5ec810879cc40ee>"recorte"]
  x27cf98eb0536b3cc(["fecha_actual"]) ==> x4b150ba8dbe4203d(["recorte_tif"])
  xc5ec810879cc40ee>"recorte"] ==> x4b150ba8dbe4203d(["recorte_tif"])
  x3d474db92cf09724>"mensaje"] ==> x0dc39fa9e42347ba>"reflectancia"]
  xfabd587be49f2fed>"fecha"] ==> x0dc39fa9e42347ba>"reflectancia"]
  xcac90a77a625823f(["render_manuscrito"])
  
  classDef default stroke:#FFC0CB,color:#FFFFFF,fill:#224289;

4.3 R

renv for environment management, listing packages and dependencies.

Log file (renv.lock) that allows environment reproducibility, with package version and location repository. Only for R packages.

4.4 R

tidyverse for general purpose data processing and manipulation.

terra for geographic data processing and reading/writing of vector/raster .

4.5 R

ggplot2 for basic static plots (.png).

ggiraph for interactive plots (.html), with more data on hover.

leaflet for interactive map creation (.html).

4.6 PYTHON

Collection
Processing level
Region of interest
Time range
Credentials

4.7 GIT

Version control management and simultaneous collaboration between project members.

GitHub for cloud storage service, sharing and project repository.

branch per member, so each one works in a specific section without interfering with the remaining repository.

pull request to request change inclusion.

merge to combine changes once checked and accepted.

4.8 QUARTO

Combines code execution from programming language and narrative text to create a output file in multiple formatted options.
Offers a publishing platform (Quarto pub) for the output as a website.

%%{
  init: {
    'themeVariables': {
      'edgeLabelBackground': '#224289',
      'edgeLabel': 'red'
    }
  }
}%%

flowchart LR
  s1[<span class="ant-design--code-filled"></span><br>scripts]:::e1 ==> q1[<span class="simple-icons--quarto"></span><br>quarto]:::e1

  s2[<span class="material-symbols--markdown"></span><br>markdown]:::e1 ===> q1

  s3[<span class="fe--document"></span><br>text]:::e1 ===> q1

  s4[<span class="file-icons--latex"></span>]:::e1 ==> q1

  q1 ==> h1[<span class="bytesize--book"></span> <span class="lineicons--www"></span><br>
            <span class="majesticons--presentation"></span> <span class="ic--round-dashboard"></span><br>
            <span class="carbon--pdf"></span> <span class="carbon--html"></span><br>
            <span class="carbon--doc"></span> <span class="carbon--ppt"></span>]:::e1

  h1 ==>|<b style='color:white'>quarto pub</b>| w1[<span class="mdi--web"></span><br>website]:::e1

  classDef e1 stroke:none,color:#FFFFFF,fill:none;

4.9 QUARTO

4.10 QUARTO

Manuscript is design for scientific document authoring, with emphasis in reproducibility, since it encourages the readers to explore processing scripts (notebooks).
Offers multiple static outputs (.pdf, .docx) that can follow a specific template.
It allows to deploy the website in Quarto Pub or GitHub Pages .
In combination with targets, plots/tables/maps are regenerated with new data input, or script modification, updating the results.

4.11 QUARTO

Files and directory tree.

quarto_manuscript
├── bibliography/
│ ├── ieee.csl
│ └── reference.bib
├── data/
│ ├── laboratory.csv
│ └── reflectance.csv
├── plots/
│ ├── boxplot.png
│ └── time_series.png
├── notebooks/
│ ├── plots.qmd
│ └── data_reading.qmd
├── raster/
├── scripts/
│ ├── functions.R
│ └── support.R
├── vectors/
├── _publish.yml
├── _quarto.yml
├── _targets.R
└── manuscript.qmd

4.12 QUARTO

_quarto.yml

project:
  type: manuscript

manuscript:
  article: manuscrito.qmd
  notebooks:
    - notebooks/data_reading.qmd

format:
  html:
    lang: es
    include-in-header:
      - extras/favicon.html
    theme:
      - extras/my_style.scss
    toc: true
    code-link: true
    code-copy: true
    tbl-cap-location: margin
    fig-cap-location: bottom
    bibliography: bibliography/reference.bib
    csl: bibliography/ieee.csl
    html-math-method: katex

manuscript.qmd

---
title: Research Project
author: Víctor Gauto
date: last modified
---

# Introducción

**Paraná River** has <i>water</i>.

````{r}
ggplot(data, aes(x, y)) +
  geom_point()
````

_publish.yml

- source: project
  quarto-pub:
    - id: ff90d76c-20c0-4210-8791-5d868ede4c50
      url: https://vhgauto.quarto.pub/gistaq-parana

5 Conclusion

A Project website was developed using Quarto Manuscript.
By combining multiple tools, the website content is updated automatically and publish.
Project members participate in the development, in charge of their own sections.
We can check the Project progress and be proud of what is done and plan what is left.

5.1 Tools learned

The website creation alongside the Project development allowed us to learn a new set of tools.

6 Future improvements

Rewrite functions used by targets.
- Define arguments clearly.
- Return descriptive messages during runtime and in case of errors.
- Incorporate website rendering.
Optimize satellite data download, avoiding to get the entire product.
- Google Earth Engine.
- rsi package.
Organice website visual features (colors, fonts, styles, margins) in the .scss file.
Use the full potential of Manuscript, so the results are created by the notebooks.

Thanks for your time

MS Víctor Gauto

victor.gauto@ca.frre.utn.edu.ar

/vhgauto

7 Resources

This presentation code is available here

Reproducible Manuscripts with Quarto - posit::conf(2023)

Quarto for Academics | Mine Çetinkaya-Rundel

Quarto | Get started

Quarto Manuscripts

Quarto Pub - Publishing service for Quarto documents

The {targets} R package user manual

Introduction to renv

R for Data Science (2e)

ggiraph-book

Quarto: The Definitive Guide

Website repository

Quarto Extensions

Official repository for Citation Style Language (CSL) citation styles

The End